.TH std::swap 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::swap \- std::swap

.SH Synopsis
   Defined in header <algorithm>        \fI(until C++11)\fP
   Defined in header <utility>          \fI(since C++11)\fP
   Defined in header <string_view>
   template< class T >                                \fI(until C++11)\fP
   void swap( T& a, T& b );
   template< class T >                                \fI(since C++11)\fP
   void swap( T& a, T& b )                            (constexpr since
   noexcept(/* see below */);                         C++20)
   template< class T2, std::size_t
   N >                              \fB(1)\fP                                \fI(until C++11)\fP
   void swap( T2 (&a)[N], T2
   (&b)[N] );
   template< class T2, std::size_t      \fB(2)\fP
   N >                                                                 \fI(since C++11)\fP
   void swap( T2 (&a)[N], T2                                           (constexpr since
   (&b)[N] ) noexcept(/* see below                                     C++20)
   */);

   Exchanges the given values.

   1) Swaps the values a and b.

   This overload participates in overload resolution only if
   std::is_move_constructible_v<T> && std::is_move_assignable_v<T> is     \fI(since C++17)\fP
   true.

   2) Swaps the arrays a and b. In effect calls std::swap_ranges(a, a + N, b).

   This overload participates in overload resolution only if              \fI(since C++17)\fP
   std::is_swappable_v<T2> is true.

.SH Parameters

   a, b      -     the values to be swapped
.SH Type requirements
   -
   T must meet the requirements of
   CopyConstructible and CopyAssignable
   \fI(until C++11)\fP
   MoveConstructible and MoveAssignable
   \fI(since C++11)\fP
   -
   T2 must meet the requirements of Swappable.

.SH Return value

   \fI(none)\fP

.SH Exceptions

   1)

   \fI(none)\fP                                              \fI(until C++11)\fP
   noexcept specification:
   noexcept(

       std::is_nothrow_move_constructible<T>::value && \fI(since C++11)\fP
       std::is_nothrow_move_assignable<T>::value

   )

   2)

   noexcept specification:
   noexcept(noexcept(swap(*a, *b)))
   The lookup for the identifier swap in the exception specification      \fI(since C++11)\fP
   finds this function template in addition to anything found by the      \fI(until C++17)\fP
   usual lookup rules, making the exception specification equivalent to
   C++17 std::is_nothrow_swappable.
   noexcept specification:                                                \fI(since C++17)\fP
   noexcept(std::is_nothrow_swappable_v<T2>)

.SH Complexity

   1) Constant.
   2) Linear in N.

.SH Specializations

   std::swap may be specialized in namespace std for program-defined
   types, but such specializations are not found by ADL (the namespace    \fI(until C++20)\fP
   std is not the associated namespace for the program-defined type).

   The expected way to make a program-defined type swappable is to provide a non-member
   function swap in the same namespace as the type: see Swappable for details.

   The following overloads are already provided by the standard library:

   std::swap(std::pair)                specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::tuple)               specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::shared_ptr)          specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::weak_ptr)            specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::unique_ptr)          specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::function)            specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_string)        specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::array)               specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::deque)               specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::forward_list)        specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::list)                specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::vector)              specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::map)                 specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::multimap)            specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::set)                 specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::multiset)            specializes the std::swap algorithm
                                       \fI(function template)\fP
   std::swap(std::unordered_map)       specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::unordered_multimap)  specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::unordered_set)       specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::unordered_multiset)  specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::queue)               specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::priority_queue)      specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::stack)               specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::valarray)            specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_stringbuf)     specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_istringstream) specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_ostringstream) specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_stringstream)  specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_filebuf)       specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_ifstream)      specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_ofstream)      specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_fstream)       specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::basic_syncbuf)       specializes the std::swap algorithm
   (C++20)                             \fI(function template)\fP
   std::swap(std::basic_spanbuf)       specializes the std::swap algorithm
   (C++23)                             \fI(function template)\fP
   std::swap(std::basic_ispanstream)   specializes the std::swap algorithm
   (C++23)                             \fI(function template)\fP
   std::swap(std::basic_ospanstream)   specializes the std::swap algorithm
   (C++23)                             \fI(function template)\fP
   std::swap(std::basic_spanstream)    specializes the std::swap algorithm
   (C++23)                             \fI(function template)\fP
   std::swap(std::basic_regex)         specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::match_results)       specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::thread)              specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function)\fP
   std::swap(std::unique_lock)         specialization of std::swap for unique_lock
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::shared_lock)         specialization of std::swap for shared_lock
   \fI(C++14)\fP                             \fI(function template)\fP
   std::swap(std::promise)             specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::packaged_task)       specializes the std::swap algorithm
   \fI(C++11)\fP                             \fI(function template)\fP
   std::swap(std::optional)            specializes the std::swap algorithm
   \fI(C++17)\fP                             \fI(function template)\fP
   std::swap(std::any)                 specializes the std::swap algorithm
   \fI(C++17)\fP                             \fI(function)\fP
   std::swap(std::variant)             specializes the std::swap algorithm
   \fI(C++17)\fP                             \fI(function template)\fP
   std::swap(std::basic_stacktrace)    specializes the std::swap algorithm
   (C++23)                             \fI(function template)\fP
   swap(std::filesystem::path)         swaps two paths
   \fI(C++17)\fP                             \fI(function)\fP
   swap(std::expected)                 specializes the std::swap algorithm
   (C++23)                             \fI(function)\fP
   swap(std::jthread)                  specializes the std::swap algorithm
   (C++20)                             \fI(function)\fP
   swap(std::move_only_function)       overloads the std::swap algorithm
   (C++23)                             \fI(function)\fP
   swap(std::stop_source)              specializes the std::swap algorithm
   (C++20)                             \fI(function)\fP
   swap(std::stop_token)               specializes the std::swap algorithm
   (C++20)                             \fI(function)\fP

.SH Example


// Run this code

 #include <algorithm>
 #include <iostream>

 namespace Ns
 {
     class A
     {
         int id {};

         friend void swap(A& lhs, A& rhs)
         {
             std::cout << "swap(" << lhs << ", " << rhs << ")\\n";
             std::swap(lhs.id, rhs.id);
         }

         friend std::ostream& operator<<(std::ostream& os, A const& a)
         {
             return os << "A::id=" << a.id;
         }

     public:
         A(int i) : id {i} {}
         A(A const&) = delete;
         A& operator = (A const&) = delete;
     };
 }

 int main()
 {
     int a = 5, b = 3;
     std::cout << a << ' ' << b << '\\n';
     std::swap(a, b);
     std::cout << a << ' ' << b << '\\n';

     Ns::A p {6}, q {9};
     std::cout << p << ' ' << q << '\\n';
 //  std::swap(p, q); // error, type requirements are not satisfied
     swap(p, q);      // OK, ADL finds the appropriate friend `swap`
     std::cout << p << ' ' << q << '\\n';
 }

.SH Output:

 5 3
 3 5
 A::id=6 A::id=9
 swap(A::id=6, A::id=9)
 A::id=9 A::id=6

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

      DR    Applied to           Behavior as published              Correct behavior
                       T was not required to be CopyConstructible
   LWG 227  C++98      or DefaultConstructible                    T is also required to
                       (a temporary object of type T might not be be CopyConstructible
                       able to be constructed)
   LWG 809  C++98      arrays could not be swapped                added overload \fB(2)\fP
                       swapping multi-dimensional arrays can
   LWG 2554 C++11      never                                      made to work
                       be noexcept due to name lookup problems

.SH See also

   ranges::swap swaps the values of two objects
   (C++20)      (customization point object)
   iter_swap    swaps the elements pointed to by two iterators
                \fI(function template)\fP
   swap_ranges  swaps two ranges of elements
                \fI(function template)\fP
   exchange     replaces the argument with a new value and returns its previous value
   \fI(C++14)\fP      \fI(function template)\fP

.SH Category:
     * conditionally noexcept
